{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial XX: Template\n",
    "\n",
    "This tutorial walks you through the process of *FILL IN*. The reason behind when and why this is important should be briefly described in the remainder of this paragraph. If possible, this should be further elucidated by a complementary figure, which can be placed in the folder *tutorials/img*. Figure 1 serves an example of this below.\n",
    "\n",
    "<img src=\"img/template_img.png\">\n",
    "\n",
    "<center>**Figure 1.** A template image</center>\n",
    "\n",
    "The remainder of this tutorial is organized as follows:\n",
    "\n",
    "* Section 1 does XXX.\n",
    "* Section 2 does YYY.\n",
    "* Section 3 does ZZZ."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Demonstrating the Functionality of Code\n",
    "\n",
    "All sections in this tutorial should consist of blocks of text describing a specific method or set of methods in Flow, following by a code snippet demonstrating the described methods being used.\n",
    "\n",
    "For example, let us say we want to show how to add two numbers in python. We might begin by introducing the numbers and methods we will use to do the addition:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = 1\n",
    "b = 2\n",
    "\n",
    "def add(a, b):\n",
    "    return a + b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we could show the functionality of the methods as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "add(a, b)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Whenever possible, sections should also be broken up into smaller subsections to help the reader more quickly identify which portion of the tutorial discusses which topic. This may be helpful to readers who are just interested in certain concept, e.g. just to find out how a specific parameter works. An example of this separation of subsections can be seen in Section 2."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Sequentially Building a Class\n",
    "\n",
    "Classes, like lines of code presented in the prior section, should be described and written sequentially rather than all at once. An example of this can be for a class version of the add method, described below.\n",
    "\n",
    "### 2.1 Introduce and Instantiate the Class\n",
    "\n",
    "We begin by defining the class with its `__init__` method, and import any necessary modules. Make sure there are enough comments in the code to make it s much self-explanatory as possible."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "\n",
    "class Adder(object):\n",
    "\n",
    "    def __init__(self, numbers):\n",
    "        \"\"\"Instantiate the Adder class.\n",
    "\n",
    "        Parameters\n",
    "        ----------\n",
    "        numbers : array_like\n",
    "            the numbers that should be added together.\n",
    "        \"\"\"\n",
    "        self.numbers = numbers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2 Include (Sequentially) New Methods\n",
    "\n",
    "Next, we add a new method to the class. We do this by recreating the class and having it inherit its previous properties. As an example of this, let us consider including a `run` method to the `Adder` class than adds the numbers that is provided to the class during instantiation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Adder(Adder):  # continuing from the previous definition of Adder\n",
    "\n",
    "    def run(self):\n",
    "        return np.sum(self.numbers)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.3 Demonstrate Functionality of the Class\n",
    "\n",
    "Finally, we can demonstrate the functionality of the class, through testing and validating the class, as seen in the code snippet below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "adder = Adder([1, 2, 3])\n",
    "\n",
    "print(\"The sum of the values is:\", adder.run())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Adding the Changes to the README and Website\n",
    "\n",
    "Once you have completed your tutorial, you must include your new tutorial in all relevant descriptors of Flow's tutorials. This include adding it to both README and the Flow Website.\n",
    "\n",
    "### 3.1 README\n",
    "\n",
    "For one, begin by adding the new tutorial to the README.md file located in the tutorials/ directory (see the figure below). This should be included in your Pull Request (PR) whenever creating a new tutorial.\n",
    "\n",
    "<img src=\"img/tutorials_readme.png\">\n",
    "\n",
    "You just need to add your tutorial with the correct number and title under the last tutorial in the README.md:\n",
    "\n",
    "`\n",
    "**Tutorial XX:** Name of your tutorial.\n",
    "`\n",
    "\n",
    "### 3.2 Website\n",
    "\n",
    "Next, you need to inform the Flow web designer to add your tutorial to the Flow website:\n",
    "\n",
    "<img src=\"img/tutorials_website.png\">\n",
    "\n",
    "To do so, send the Title and the Github link to your tutorial to the Flow web designer."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
